<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="stylesheet" href="style.css" type="text/css" />

<title>classpath.files</title>
</head>
<body>

<h2><a name="classpath.files">classpath.files</a></h2>
<p>
The <code>classpath.files</code> element produces a FileSet containing libraries and classfiles
that are contributed directly or indirectly to the classpath of a project.
</p>
<p>
By default, all application libraries, and all class files or other resources in output folders
are included in the FileSet. The criteria for what classpath entries are selected for inclusion
may optionally be specified by one or more child <code>&lt;select&gt;</code> elements.
</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <th valign="top">Attribute</th>
    <th valign="top">Description</th>
    <th align="center" valign="top">Required</th>
  </tr>
  <tr>
    <td valign="top">exportedonly</td>
    <td valign="top">
    	If false, all classpath entries are included.
    	If true, for dependent projects, only exported classpath entries are included.
    </td>
    <td valign="top" align="center">No; defaults to false.</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
    <td valign="top">
    	If false, log a warning message, but do not stop execution if an error occurs.
    	If true, an exception is thrown when an error occurs.
    </td>
    <td valign="top" align="center">No; defaults to true.</td>
  </tr>
  <tr>
    <td valign="top">project</td>
    <td valign="top">Specifies the project whose classpath will be traversed.</td>
    <td valign="top" align="center">
    	No; defaults to the project containing the invoked Ant buildfile.
    </td>
  </tr>
  <tr>
    <td valign="top">traverse</td>
    <td valign="top">
    	Specifies whether the classpaths for other projects referenced directly
    	or indirectly by the classpath should also be traversed. If true, all
    	references on the classpath will be traversed. If false, classpath entries
    	for referenced projects will not be included.
    </td>
    <td valign="top" align="center">
    	No; defaults to true.
    </td>
  </tr>
</table>

<h3>Parameters specified as nested elements</h3>
<h4><code><a name="nested_select">select</a></code></h4>
<p>
One or more child <code>&lt;select&gt;</code> elements may be
used within a <code>&lt;classpath.files&gt;</code> element to specify
the criteria for selecting classpath entries. The resources referenced
by selected classpath entries will be included in the FileSet. If
provided, only classpath entries that satisfy the criteria of <em>at least one</em> of
the <code>&lt;select&gt;</code> elements will be selected. Selection criteria are
specified via attributes on the <code>&lt;select&gt;</code> elements. <em>All</em>
of the criteria specified by the attributes on any particular <code>&lt;select&gt;</code>
element must be satisfied for any particular classpath entry to be
selected by that element. In other words, there is an implicit <em>or</em>
relationship between multiple nested <code>&lt;select&gt;</code>
elements, and an implicit <em>and</em> relationship between multiple
attributes on any single <code>&lt;select&gt;</code> element.
</p>
<p>
<a name="classpath_entry_kind">Not all classpath entries</a> correspond
to files on the classpath; some are used to indirectly reference other
resources that are contributed to the classpath. Projects and user
libraries are examples of this. All classpath entries have an associated
<dfn>kind</dfn> that indicates the nature of the entry, and which may be
specified in selection criteria. The identifiers used to specify <dfn>kinds</dfn>
are the same used within an Eclipse project's <code>.classpath</code>
file. The various kinds are:
</p>
<table class="simplelist">
	<tr>
		<td valign="top"><code>project</code></td>
		<td>A Java project</td>
	</tr>
	<tr>
		<td valign="top"><a name="kind.container"><code>con</code></a></td>
		<td>
			A classpath container. Classpath containers can reference libraries or projects and contribute them
			to the classpath. A classpath container may be a user library, a system library contributed by the platform
			&ndash; e.g. the JRE System Library contributed to classpaths by Eclipse, 
			or a custom container contributed by a plugin. A classpath container is identified by a unique name
			within the scope of any particular project.
		</td>
	</tr>
	<tr>
		<td valign="top"><code>lib</code></td>
		<td>
			A library file or folder. A library may be contributed to the classpath by a project or
			a classpath container.
		</td>
	</tr>
	<tr>
		<td valign="top"><code>src</code></td>
		<td>
			A source folder. Resources in source folders are not directly contributed to the classpath and will not
			be selected by the <code>&lt;classpath.files&gt;</code> type. However, a source folder will provide
			resources that end up in an output folder &ndash; either one explicitly associated with the source folder,
			or the default output folder associated with its parent project.
		</td>
	</tr>
	<tr>
		<td valign="top"><code>output</code></td>
		<td>
			An output folder &ndash; either one associated with a source folder, or the default output folder
			for a project.
		</td>
	</tr>
</table>
<p>
In addition, classpath containers each have an associated <a name="container.kinds"><dfn>container kind</dfn></a>.
This will be one of:
</p>
<table class="simplelist">
	<tr>
		<td valign="top"><code>application</code></td>
		<td>
			A container that maps to an application library &ndash; e.g. a User Library
			added by the user.
		</td>
	</tr>
	<tr>
		<td valign="top"><code>system</code></td>
		<td>
			A container that maps to a system library.
		</td>
	</tr>
	<tr>
		<td valign="top"><code>default-system</code></td>
		<td>
			A container that maps to a default system library, implicitly contributed by the runtime.
		</td>
	</tr>
</table>
<p>
<a href="http://ant.apache.org/manual/CoreTypes/patternset.html">PatternSets</a> may optionally be specified
as nested <code>&lt;patternset&gt;</code> elements. If specified, these apply to the names of folders or
library files that are referenced as classpath entries. They are not used to filter individual resources contained
<em>within</em> library or output folders. In addition, the <code>&lt;select&gt;</code> element itself is an
implicit PatternSet and supports the nested <code>&lt;include&gt;</code>, <code>&lt;includesfile&gt;</code>,
<code>&lt;exclude&gt;</code> and <code>&lt;excludesfile&gt;</code> elements of PatternSet directly, 
as well as PatternSet's attributes. For workspace resources, the name used for pattern matching will be
the workspace-relative resource path. For libraries external to the workspace, the name used will be the
native path of the filesystem location.
</p>
<p>Selection criteria for <code>&lt;select&gt;</code> elements are specified with the following attributes.</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <th valign="top">Attribute</th>
    <th valign="top">Description</th>
    <th align="center" valign="top">Required</th>
  </tr>
  <tr>
    <td valign="top">container</td>
    <td valign="top">
    	Specifies the name of the classpath container that contributed a selected entry to the classpath.
    	Simple wildcards &ndash; "*" or "?" &ndash; may be used to specify a pattern.
    </td>
    <td valign="middle" align="center" rowspan="5">
    	At least one attribute must be set to provide selection criteria.
    </td>
  </tr>
  <tr>
    <td valign="top">containerkinds</td>
	<td valign="top">
		<p>Only applicable for libraries contributed by classpath containers 
		(<code>srckind="con"</code>). Specifies a space-delimited list of one or more
		<a href="#container.kinds">container kinds</a>. This may either be
		a numeric code, or one of: <code>application</code>, <code>system</code>,
		or <code>default-system</code>.</p>
		<p><em>Note:</em> If neither <code>container</code> nor <code>containerkinds</code>
		is specified, then by default, <dfn>container kinds</dfn> other than <code>application</code>
		are excluded.</p>
	</td>
  </tr>
  <tr>
    <td valign="top">kind</td>
    <td valign="top">
    	Specifies the <dfn>kind</dfn> of classpath entry to select. Valid <dfn>kinds</dfn> are
    	<code>lib</code> and <code>output</code>.
    </td>
  </tr>
  <tr>
    <td valign="top">srckind</td>
    <td valign="top">
    	Specifies the <dfn>kind</dfn> of classpath entry that contributed any selected entry
    	to the classpath. Valid <dfn>srckinds</dfn> are <code>project</code>, <code>con</code>,
    	and <code>src</code>.
    </td>
  </tr>
  <tr>
    <td valign="top">type</td>
    <td valign="top">
    	Only applicable for libraries (<code>kind="lib"</code>). If <code>file</code>, specifies
    	that only JAR or ZIP file libraries are selected. If <code>dir</code> or <code>folder</code>,
    	only library folders or directories are selected. If ommitted, both libary files and folders
    	are selected.
    </td>
  </tr>
</table>

<h4>Examples</h4>
<blockquote><pre>
&lt;classpath.files/&gt;
</pre></blockquote>
<p>Creates a FileSet containing all library files, and all resources in library folders or
output folders that are directly or indirectly referenced on the classpath for the project
containing the invoked ant buildfile, excluding only libraries contributed by classpath containers
that map to system libraries.</p>

<blockquote><pre>
&lt;classpath.files project=&quot;test-proj&quot; traverse=&quot;false&quot;&gt;
  &lt;select kind=&quot;lib&quot; type=&quot;file&quot;&gt;
    &lt;exclude name=&quot;**/http-*.jar&quot;/&gt;
  &lt;/select&gt;
&lt;/classpath.files&gt;
</pre></blockquote>
<p>Creates a FileSet containing all library files referenced on the classpath of the project "test-proj", but
not including those contributed by the classpaths of other projects. Any JAR files whose names begin
with "http-" are excluded.</p>

<blockquote><pre>
&lt;classpath.files&gt;
  &lt;select kind=&quot;lib&quot; container=&quot;org.apache.ivyde.eclipse.cpcontainer.IVYDE_CONTAINER/*&quot;/&gt;
  &lt;select kind=&quot;lib&quot; type=&quot;file&quot; srckind=&quot;project&quot;/&gt;
&lt;/classpath.files&gt;
</pre></blockquote>
<p>Creates a FileSet containing all library files referenced directly on the classpath by a project, or 
contributed to the classpath by classpath containers whose name begins with 
"<code>org.apache.ivyde.eclipse.cpcontainer.IVYDE_CONTAINER/</code>". (The latter would select
libraries contributed to the classpath by the <a href="http://ant.apache.org/ivy/ivyde/">IvyDE</a> plugin.
Previous versions used "<code>org.jayasoft.ivyde.eclipse.cpcontainer.IVYDE_CONTAINER/</code>" as the prefix
for their container names.)</p>

<blockquote><pre>
&lt;classpath.files&gt;
  &lt;select kind=&quot;output&quot; srckind=&quot;project&quot;/&gt;
&lt;/classpath.files&gt;
</pre></blockquote>
<p>Creates a FileSet containing all resources contained within the default
output folders for projects referenced directly or indirectly on the classpath.</p>

<blockquote><pre>
&lt;classpath.files&gt;
  &lt;select kind=&quot;output&quot; srckind=&quot;src&quot;/&gt;
&lt;/classpath.files&gt;
</pre></blockquote>
<p>Creates a FileSet containing all resources contained within the output folders for 
any source folders on the classpath, but not the default output folders for any projects.</p>

<blockquote><pre>
&lt;classpath.files&gt;
  &lt;select kind=&quot;output&quot;/&gt;
&lt;/classpath.files&gt;
</pre></blockquote>
<p>Creates a FileSet containing all resources contained within any output folders associated
with any source folders or projects on the classpath.</p>

<blockquote><pre>
&lt;sync todir=&quot;${dist.dir}/WEB-INF/lib&quot;&gt;
  &lt;classpath.files&gt;
    &lt;select kind=&quot;lib&quot; container=&quot;org.maven.ide.eclipse.MAVEN2_CLASSPATH_CONTAINER/*&quot;/&gt;
    &lt;select kind=&quot;lib&quot; type=&quot;file&quot; srckind=&quot;project&quot;/&gt;
  &lt;/classpath.files&gt;
&lt;/sync&gt;

&lt;sync todir=&quot;${dist.dir}/WEB-INF/classes&quot;&gt;
  &lt;classpath.files&gt;
    &lt;select kind=&quot;output&quot;/&gt;
  &lt;/classpath.files&gt;
&lt;/sync&gt;
</pre></blockquote>
<p>
This example synchronizes the "WEB-INF/lib" subdirectory of the directory 
designated by the <code>dist.dir</code> property from a FileSet containing 
all library files referenced directly on the classpath by a project, or 
contributed to the classpath by classpath containers whose name begins with 
"<code>org.maven.ide.eclipse.MAVEN2_CLASSPATH_CONTAINER/</code>".
(The latter would select libraries contributed to the classpath by the 
<a href="http://m2eclipse.sonatype.org/">M2Eclipse</a> plugin.)
</p>
<p>
It then synchronizes the "WEB-INF/lib" subdirectory of the directory designated by 
the <code>dist.dir</code> from a FileSet contaning all resources contained 
within any output folders on the classpath.
</p>

</body>
</html>